feat(docs): add documentation for `doc-kit` by bmuenzenmeyer · Pull Request #889 · nodejs/doc-kit

bmuenzenmeyer · 2026-07-10T21:15:19Z

Description

Introduces the doc-kit documentation site, built with doc-kit!
This also serves as a reasonable simple web example.

Validation

npm run docs:build
npx serve www/out

Getting started suggestion end-state

Related Issues

Check List

I have read the Contributing Guidelines and made commit messages that follow the guideline.
I have run node --run test and all tests passed.
I have check code formatting with node --run format & node --run lint.
I've covered new added functionality with unit tests if necessary.

… the spec

vercel · 2026-07-10T21:15:24Z

The latest updates on your projects. Learn more about Vercel for GitHub.

Project	Deployment	Actions	Updated (UTC)
api-docs-tooling	Ready	Preview	Jul 12, 2026 3:51am

codecov · 2026-07-10T21:16:09Z

Codecov Report

❌ Patch coverage is 0% with 260 lines in your changes missing coverage. Please review.
✅ Project coverage is 83.87%. Comparing base (d7bdf39) to head (3f035e7).
⚠️ Report is 5 commits behind head on main.

Files with missing lines	Patch %	Lines
www/theme/SideBar.jsx	0.00%	103 Missing ⚠️
scripts/build-docs-content.mjs	0.00%	82 Missing ⚠️
www/doc-kit.config.mjs	0.00%	75 Missing ⚠️

Additional details and impacted files

@@            Coverage Diff             @@
##             main     #889      +/-   ##
==========================================
- Coverage   85.04%   83.87%   -1.18%     
==========================================
  Files         179      183       +4     
  Lines       16496    16826     +330     
  Branches     1500     1513      +13     
==========================================
+ Hits        14029    14112      +83     
- Misses       2457     2704     +247     
  Partials       10       10

☔ View full report in Codecov by Harness.
📢 Have feedback on the report? Share it here.

🚀 New features to boost your workflow:

📦 JS Bundle Analysis: Save yourself from yourself by tracking and limiting bundle sizes in JS merges.

github-actions · 2026-07-10T21:17:40Z

`web` Generator

File	Base	Head	Diff
`all.html`	19.94 MB	19.94 MB	-234.00 B (-0.00%)

AugustinMauroy

Noice !

also we should add a "why doc-kit" section but with a "TBD" and in future have comparison with fuma-docs/docausorus ...

AugustinMauroy · 2026-07-11T10:32:12Z

if I recall correctly on this file we can customize the color theme.
And IMO we should change it. Why not keep green ? this green will be understood as nodejs runtime related. so for undici, learn it's work well. But if we want to as general propose tool we should chose another colors.
Also it's good example of how can this be customized.

I opted to re-write the custom-properties. i dont think head theme is enough, AFAIK
I purposely made a couple other customizations

humm intresting

AugustinMauroy · 2026-07-11T10:33:03Z

+      - name: Upload site artifact
+        uses: actions/upload-artifact@043fb46d1a93c77aae656e7c1c64a875d1fc6a0a # v7.0.1
+        with:
+          name: docs-site
+          path: www/out


what if we deploy the docs on GH page ?

i dont have strong opinions here other that continuing our current patterns.

cursor · 2026-07-12T02:20:16Z

PR Summary

Low Risk
Docs-only build pipeline, config, and markdown heading tweaks; no changes to core generator runtime behavior beyond what the site build invokes.

Overview
Adds a documentation site built with doc-kit’s own web and orama-db targets, plus CI that verifies the build on every PR and push to main.

A new docs:build flow runs scripts/build-docs-content.mjs to merge www/pages/*.md, root docs/*.md, and each generator’s README.md into gitignored www/content/, then generates static output under www/out/ via www/doc-kit.config.mjs (flat URLs, no synthetic Node.js index page, custom meta, repo-level edit link). GitHub Actions (docs.yml) runs npm ci and node --run docs:build, uploading www/out as an artifact.

Authoring includes new home and getting-started pages and a custom SideBar that splits “Pages” vs “Generators”, fixes guide order, and renders backtick headings as inline code. Generator READMEs are retitled from ## to # so they read correctly when pulled into the site. Minor tooling tweaks: ignore/format www/content, Prettier proseWrap for www/pages, and a target example in docs/configuration.md.

^{Reviewed by Cursor Bugbot for commit 3f035e7. Bugbot is set up for automated code reviews on this repo. Configure here.}

cursor · 2026-07-12T02:21:34Z

+
+node bin/cli.mjs generate \
+  --config-file ./www/doc-kit.config.mjs \
+  --log-level info


Build script ignores content failure

High Severity

The docs build shell script runs content assembly and doc-kit generate as separate commands without failing fast. If build-docs-content.mjs exits non-zero, the generator still runs, so node --run docs:build and CI can succeed with missing or stale www/content/.

^{Reviewed by Cursor Bugbot for commit 0f9fb0f. Configure here.}

cursor · 2026-07-12T02:21:34Z

+      links: [],
+      html: [],
+    },
+  },


Node banner on doc-kit site

Medium Severity

The documentation site config customizes web branding but leaves the default remoteConfigUrl pointing at nodejs.org. The layout still loads remote Node.js announcement banners on the doc-kit docs site instead of a neutral or empty banner config.

^{Reviewed by Cursor Bugbot for commit 0f9fb0f. Configure here.}

avivkeller · 2026-07-12T02:22:47Z

+ *
+ * @returns {Promise<Array<{ name: string, markdown: string }>>}
+ */
+const collectPages = async () => {


Would it be better to use a glob for this?

**/*.md?

i dont have strong opinions either way, but knew that i

wanted to clean out

load very specific subset of three possible patterns, but perhaps not other future markdown.

avivkeller · 2026-07-12T02:24:04Z

+The `legacy-html-all` target has no additional dependencies and is the quickest
+way to see output:


What does "no additional dependencies" mean? It depends on other generators (e.g. AST)

to run in the browser. it's html

avivkeller · 2026-07-12T02:25:34Z

+- [Further customize the `web` generator](./generator-web) — check out more
+  customization options
+- [Read the full input specification](./specification) — the full Markdown
+  contract. components.


What's . components.?

lol can you tell i am typing this while watching the world cup?

avivkeller · 2026-07-12T02:29:20Z

+    // Pages are assembled into `www/content/` at build time, so there is no
+    // single source file a `{path}` template could point at. Link to the repo
+    // instead; a per-page link would need a `#theme/Metabar` override that maps
+    // each slug back to its true origin.
+    editURL: `https://github.com/${REPOSITORY}`,


We can also leave this blank to remove the link entirely

Co-authored-by: Aviv Keller <me@aviv.sh>

cursor · 2026-07-12T03:24:11Z

+
+await Promise.all(
+  pages.map(({ name, markdown }) => writeFile(join(CONTENT, name), markdown))
+);


Silent duplicate content filenames

Medium Severity

collectPages merges www/pages, docs, and generator READMEs into one list keyed only by basename. Two sources with the same .md filename write to one path with no warning; whichever write finishes last wins and the other source’s page disappears from the built site.

^{Reviewed by Cursor Bugbot for commit b714583. Configure here.}

Co-authored-by: Aviv Keller <me@aviv.sh>

cursor

Cursor Bugbot has reviewed your changes using default effort and found 1 potential issue.

There are 4 total unresolved issues (including 3 from previous reviews).

^{❌ Bugbot Autofix is OFF. To automatically fix reported issues with cloud agents, enable autofix in the Cursor dashboard.}

^{Reviewed by Cursor Bugbot for commit 3f035e7. Configure here.}

AugustinMauroy · 2026-07-12T09:28:31Z

missing link to orama docs

a good follow up

bmuenzenmeyer added 4 commits July 10, 2026 16:08

setup CICD

c5118db

adds doc kit docs

139fcb4

reminds people that target can be supplied by config, not just flags

cdb9458

promote every heading up a level to make doc-kit rendering easier per…

1d783e3

… the spec

fix lint

09e884c

vercel Bot deployed to Preview July 11, 2026 00:23 View deployment

This was referenced Jul 11, 2026

fix(remark): preserve code display names through raw HTML #879

Merged

web generator should not render the search bar if orama-db is not enabled #891

Open

Support mermaid diagrams #892

Open

bmuenzenmeyer added 2 commits July 10, 2026 22:03

improve home page content, making sure to format pages

ec0d712

slight tweaks to getting started

65c26db

AugustinMauroy reviewed Jul 11, 2026

View reviewed changes

bmuenzenmeyer added 2 commits July 11, 2026 11:51

use node directly rather than npm

9426ef2

improve documentation based on feedback

82e80ef

vercel Bot deployed to Preview July 12, 2026 02:12 View deployment

add showcase

0f9fb0f

bmuenzenmeyer marked this pull request as ready for review July 12, 2026 02:20

bmuenzenmeyer requested a review from a team as a code owner July 12, 2026 02:20

vercel Bot deployed to Preview July 12, 2026 02:20 View deployment

cursor Bot reviewed Jul 12, 2026

View reviewed changes

avivkeller changed the title ~~Doc kit docs~~ feat(docs): add documentation for doc-kit Jul 12, 2026

avivkeller reviewed Jul 12, 2026

View reviewed changes

bmuenzenmeyer and others added 4 commits July 11, 2026 22:21

Update www/pages/index.md

a49ea50

Co-authored-by: Aviv Keller <me@aviv.sh>

Update scripts/vercel-docs-build.sh

c7d5a19

Co-authored-by: Aviv Keller <me@aviv.sh>

Update www/pages/getting-started.md

9e7655c

Co-authored-by: Aviv Keller <me@aviv.sh>

Update www/pages/index.md

1f554c1

Co-authored-by: Aviv Keller <me@aviv.sh>

Update www/pages/getting-started.md

b714583

Co-authored-by: Aviv Keller <me@aviv.sh>

cursor Bot reviewed Jul 12, 2026

View reviewed changes

vercel Bot deployed to Preview July 12, 2026 03:24 View deployment

Update www/pages/index.md

642a641

Co-authored-by: Aviv Keller <me@aviv.sh>

vercel Bot deployed to Preview July 12, 2026 03:26 View deployment

format after reviews

c0cb3d9

vercel Bot deployed to Preview July 12, 2026 03:49 View deployment

better consistency

3f035e7

vercel Bot deployed to Preview July 12, 2026 03:51 View deployment

cursor Bot reviewed Jul 12, 2026

View reviewed changes

Comment thread scripts/build-docs-content.mjs

AugustinMauroy reviewed Jul 12, 2026

View reviewed changes

		The `legacy-html-all` target has no additional dependencies and is the quickest
		way to see output:

Uh oh!

Conversation

bmuenzenmeyer commented Jul 10, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Description

Validation

Related Issues

Check List

Uh oh!

vercel Bot commented Jul 10, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

codecov Bot commented Jul 10, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Codecov Report

Uh oh!

github-actions Bot commented Jul 10, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

web Generator

Uh oh!

AugustinMauroy left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

cursor Bot commented Jul 12, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

PR Summary

Uh oh!

cursor Bot Jul 12, 2026

Choose a reason for hiding this comment

Build script ignores content failure

Uh oh!

cursor Bot Jul 12, 2026

Choose a reason for hiding this comment

Node banner on doc-kit site

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

cursor Bot Jul 12, 2026

Choose a reason for hiding this comment

Silent duplicate content filenames

Uh oh!

cursor Bot left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

bmuenzenmeyer commented Jul 10, 2026 •

edited

Loading

vercel Bot commented Jul 10, 2026 •

edited

Loading

codecov Bot commented Jul 10, 2026 •

edited

Loading

github-actions Bot commented Jul 10, 2026 •

edited

Loading

`web` Generator

cursor Bot commented Jul 12, 2026 •

edited

Loading